includes/filerepo/backend/filejournal/FileJournal.php

   1 <?php
   2 /**
   3  * @defgroup FileJournal File journal
   4  * @ingroup FileBackend
   5  */
   6
   7 /**
   8  * @file
   9  * @ingroup FileJournal
  10  * @author Aaron Schulz
  11  */
  12
  13 /**
  14  * @brief Class for handling file operation journaling.
  15  *
  16  * Subclasses should avoid throwing exceptions at all costs.
  17  *
  18  * @ingroup FileJournal
  19  * @since 1.20
  20  */
  21 abstract class FileJournal {
  22         protected $backend; // string
  23         protected $ttlDays; // integer
  24
  25         /**
  26          * Construct a new instance from configuration.
  27          * $config includes:
  28          *     'ttlDays' : days to keep log entries around (false means "forever")
  29          *
  30          * @param $config Array
  31          */
  32         protected function __construct( array $config ) {
  33                 $this->ttlDays = isset( $config['ttlDays'] ) ? $config['ttlDays'] : false;
  34         }
  35
  36         /**
  37          * Create an appropriate FileJournal object from config
  38          *
  39          * @param $config Array
  40          * @param $backend string A registered file backend name
  41          * @return FileJournal
  42          */
  43         final public static function factory( array $config, $backend ) {
  44                 $class = $config['class'];
  45                 $jrn = new $class( $config );
  46                 if ( !$jrn instanceof self ) {
  47                         throw new MWException( "Class given is not an instance of FileJournal." );
  48                 }
  49                 $jrn->backend = $backend;
  50                 return $jrn;
  51         }
  52
  53         /**
  54          * Get a statistically unique ID string
  55          *
  56          * @return string <9 char TS_MW timestamp in base 36><22 random base 36 chars>
  57          */
  58         final public function getTimestampedUUID() {
  59                 $s = '';
  60                 for ( $i = 0; $i < 5; $i++ ) {
  61                         $s .= mt_rand( 0, 2147483647 );
  62                 }
  63                 $s = wfBaseConvert( sha1( $s ), 16, 36, 31 );
  64                 return substr( wfBaseConvert( wfTimestamp( TS_MW ), 10, 36, 9 ) . $s, 0, 31 );
  65         }
  66
  67         /**
  68          * Log changes made by a batch file operation.
  69          * $entries is an array of log entries, each of which contains:
  70          *     op      : Basic operation name (create, store, copy, delete)
  71          *     path    : The storage path of the file
  72          *     newSha1 : The final base 36 SHA-1 of the file
  73          * Note that 'false' should be used as the SHA-1 for non-existing files.
  74          *
  75          * @param $entries Array List of file operations (each an array of parameters)
  76          * @param $batchId string UUID string that identifies the operation batch
  77          * @return Status
  78          */
  79         final public function logChangeBatch( array $entries, $batchId ) {
  80                 if ( !count( $entries ) ) {
  81                         return Status::newGood();
  82                 }
  83                 return $this->doLogChangeBatch( $entries, $batchId );
  84         }
  85
  86         /**
  87          * @see FileJournal::logChangeBatch()
  88          *
  89          * @param $entries Array List of file operations (each an array of parameters)
  90          * @param $batchId string UUID string that identifies the operation batch
  91          * @return Status
  92          */
  93         abstract protected function doLogChangeBatch( array $entries, $batchId );
  94
  95         /**
  96          * Get an array of file change log entries.
  97          * A starting change ID and/or limit can be specified.
  98          *
  99          * The result as a list of associative arrays, each having:
 100          *     id         : unique, monotonic, ID for this change
 101          *     batch_uuid : UUID for an operation batch
 102          *     backend    : the backend name
 103          *     op         : primitive operation (create,update,delete)
 104          *     path       : affected storage path
 105          *     path_sha1  : base 36 sha1 of the affected storage path
 106          *     timestamp  : TS_MW timestamp of the batch change
 107
 108          * Also, $next is updated to the ID of the next entry.
 109          *
 110          * @param $start integer Starting change ID or null
 111          * @param $limit integer Maximum number of items to return
 112          * @param &$next string
 113          * @return Array
 114          */
 115         final public function getChangeEntries( $start = null, $limit = 0, &$next = null ) {
 116                 $entries = $this->doGetChangeEntries( $start, $limit ? $limit + 1 : 0 );
 117                 if ( $limit && count( $entries ) > $limit ) {
 118                         $last = array_pop( $entries ); // remove the extra entry
 119                         $next = $last['id']; // update for next call
 120                 } else {
 121                         $next = null; // end of list
 122                 }
 123                 return $entries;
 124         }
 125
 126         /**
 127          * @see FileJournal::getChangeEntries()
 128          * @return Array
 129          */
 130         abstract protected function doGetChangeEntries( $start, $limit );
 131
 132         /**
 133          * Purge any old log entries
 134          *
 135          * @return Status
 136          */
 137         final public function purgeOldLogs() {
 138                 return $this->doPurgeOldLogs();
 139         }
 140
 141         /**
 142          * @see FileJournal::purgeOldLogs()
 143          * @return Status
 144          */
 145         abstract protected function doPurgeOldLogs();
 146 }
 147
 148 /**
 149  * Simple version of FileJournal that does nothing
 150  * @since 1.20
 151  */
 152 class NullFileJournal extends FileJournal {
 153         /**
 154          * @see FileJournal::logChangeBatch()
 155          * @return Status
 156          */
 157         protected function doLogChangeBatch( array $entries, $batchId ) {
 158                 return Status::newGood();
 159         }
 160
 161         /**
 162          * @see FileJournal::doGetChangeEntries()
 163          * @return Array
 164          */
 165         protected function doGetChangeEntries( $start, $limit ) {
 166                 return array();
 167         }
 168
 169         /**
 170          * @see FileJournal::purgeOldLogs()
 171          * @return Status
 172          */
 173         protected function doPurgeOldLogs() {
 174                 return Status::newGood();
 175         }
 176 }